[SQL] Add short-term backup retention immutability support - #34207

🤖 PR Validation — ⚠️ Review suggested

Related command

• az sql db str-policy set, show, and wait
• az sql midb short-term-retention-policy set and show (live and restorable dropped databases)

Description
Add short-term backup immutability support using 2026-08-01-preview, with the final async SET result aligned with Azure PowerShell PR 30215.

• Add nullable --lock-immutability and --yes/-y to both SET commands. Only true prompts, with an irreversible-action warning. Decline/non-interactive confirmation failure sends no update and emits no result; --yes bypasses confirmation.
• Reject --lock-immutability with --deleted-time, including explicit false, before HTTP. Never serialize that property for dropped MI databases.
• Surface the service's immutabilityStatus on SET/show for SQL Database and live/dropped MI databases, retaining flattened CLI output and nested systemData.
• SQL Database retention remains optional for differential-only input; omitted settings are not serialized as null. MI retention remains required, including support for zero on dropped databases. SQL DB lock-only input is serializable but is rejected by the tested service; the corrected help example supplies explicit retention.
• Keep the focused SDK-independent shared AAZ HTTP/polling implementation and existing registrations, cloud endpoints, authentication, URL escaping, --ids, wait and --no-wait. azure-mgmt-sql==4.0.0b22 is unchanged; a whole-module migration to the hybrid models in 5.0.0b2 is out of scope.

Final policy GET alignment (2026-10-13)

Commit 93e16b8f2253fbdccb1a8337cc2dca763d6cae83 removes the explicit final-state-via: location override from the shared STR PUT operation. For the Azure-AsyncOperation flow recorded for SQL Database and MI:

1. PUT the policy.
2. Poll async status until Succeeded.
3. GET the original policy resource URL and return that policy.

This matches the PowerShell recordings, whose final policy GET belongs to the SET operation. It replaces the previous OperationResults GET; it does not add a second final read, synthesize Locked, retry until a desired immutability status, add fixed delays, or fill omitted request properties.

• --no-wait still submits once, without polling or a final GET, and emits no result.
• Failed/canceled operations propagate their error before any final GET. Errors from the final policy GET are also propagated.
• Synchronous 200 responses without polling headers and Location-only responses retain standard ARM behavior: return their response without an additional policy GET. Unit tests cover these distinct paths; no unconditional readback is claimed.
• SQL DB and MI locking scenarios now assert Locked on SET itself, as well as through independent policy GETs. All five affected scenarios were genuinely re-recorded live on 2026-10-13; response statuses and URLs were not hand-edited to pass playback.
• Fixed the recording sanitizer to preserve non-JSON/non-object gateway responses instead of masking HTTP retry/error handling with a JSON parsing exception.
• Isolated process-wide CLI session caches in unit-test setup/cleanup so temporary configuration directories do not contaminate later scenario tests. Help regression coverage tolerates normal line wrapping.

Wait-command compatibility

The earlier fix in 3333619a720b9deb77c784134f1e276500dda0c4 remains intact: az sql db str-policy wait --policy-name default is accepted and --policy-name remains required, matching the exact PR base cc010d2104b3ab0089c33fb7eac8816c260a11ac. A dedicated getter forwards and URL-escapes the supplied name; show/set and MI commands still use the default policy without a new public option. Regression coverage includes --ids, encoded names and missing-option rejection without HTTP. No compatibility-rule suppression or exception is requested.

Remaining service limitations and release checks

• OperationResults can still report Disabled while the actual policy GET reports Locked. Earlier raw SQL DB recordings and 24 paired MI diagnostic reads over approximately 144 seconds demonstrated this backend inconsistency. The CLI now uses the standard final policy GET for the recorded async flow; this does not claim the backend endpoint is fixed.
• New SQL DB policies may initially report Disabled before becoming Enabled. The new-DB locking test retains its 900-second readiness timeout and refuses to lock before Enabled; independent post-lock checks retain their 300-second timeout. A previous Oct13 initialization failure is not counted as passing. The refreshed new-DB locking recording passed.
• The tested SQL DB backend rejects lock-only PUTs with InvalidParameterValue; including current retention succeeds. On a locked policy, retention updates with the lock flag omitted can be interpreted as unlocking. Help now documents explicit retention when locking and preserving --lock-immutability true when increasing retention. No automatic payload completion was introduced.
• Confirm preview API rollout for intended regions/clouds and obtain maintainer approval before release. This PR remains a draft.

Testing Guide

Latest local result: 44 tests passed, zero failures/errors/skips (28 CLI/HTTP unit tests + 11 scenario safety tests + 5 recorded scenarios). Offline execution used this checkout's CLI/core/test SDK source with the installed CLI libraries on Python 3.14.6, an empty Azure configuration, live-target flags removed, socket connections blocked, and only the unrelated release-update connectivity probe disabled.

The new original-resource final-GET regressions failed against the previous Location override and passed after the fix. A combined-suite run also exposed and fixed the unit-test session-cache isolation issue; the complete combined suite then passed in 70.238 seconds.

SQL Database scenarios

Source: SQL Database STR tests.

All three refreshed SQL DB scenarios passed live on 2026-10-13 (new DBs in West US 2; policy-only in West Central US), and passed offline playback. The two new SQL DBs were retained by request. There are now eight retained SQL test databases across the earlier and current validation runs; they continue to incur charges. The policy-only run modifies only its expressly authorized retained test DB, not an original database.

SQL Managed Instance scenarios

Source: SQL MI STR tests.

Both refreshed MI recordings passed live in West Central US on 2026-10-13 and offline playback. Earlier attempts encountered a non-JSON response and an interrupted backup-readiness wait; these are not counted as successful recordings and were superseded by complete passing captures. All MI test databases from these attempts were cleaned up, including failed-attempt databases. The seven original MI database names remain unchanged; locked dropped backups are not purged and remain for their retention period.

Offline regressions, audits and CI

• 28 CLI/HTTP unit tests: confirmation accept/decline/no-TTY/yes; omitted/false lock; request omission and integer/Boolean serialization; dropped-MI true/false rejection, zero retention, timestamp addressing; all three statuses; flattened output and nested systemData; required wait policy-name compatibility; IDs and help. Polling coverage includes async-only/both headers for all three resource types, InProgress → Succeeded → original policy GET, synchronous200, Location-only, no-wait request counts, Failed/Canceled without final read, final-GET403/404 propagation, and actual CLI SET JSON output. Lock-only serialization coverage does not imply live support.
• 11 scenario safety tests: six SQL DB tests for explicit targets, own-resource/policy-only write guards, keep-database behavior and bounded policy waits; five MI tests for target/write scope, signed-URL sanitization, non-JSON/non-object preservation and live/dropped policy waits.
• Recording audit passed for all five captures: real target names/subscription IDs and credential markers absent; signed polling parameters redacted; unrelated dropped databases filtered. Every recorded completed async STR SET uses the policy GET, with five Locked SET results across the three locking scenarios. No STR OperationResults GET remains in these captures. No-wait SETs have no polling/final reads.
• Write-scope audit and post-run inventory/policy checks passed: prior database inventories preserved, only the two approved SQL DB additions remain, other retained test policies unchanged, and all MI attempt DBs removed. No server, MI or resource-group write is permitted by the guards; original databases are untouched.
• Targeted pycodestyle, git diff --check, and editor diagnostics passed. The shared STR operation module passed Pylint at 10.00/10. Full local SQL-module Pylint is not claimed because the installed runtime has compiled-only dependencies and previously reported unrelated findings.
• Hosted main/full-test/breaking-change/lint/style checks passed for the prior head 3333619a.... Checks for this new head 93e16b8f2253fbdccb1a8337cc2dca763d6cae83 must run independently; earlier green checks or bot summaries are not validation of this commit.

Hosted pipeline gate: Requested /azp run for this head, but the Azure Pipelines bot reported insufficient commenter privileges. A maintainer must trigger the main/full-test/breaking-change pipelines. The independent azdev-linter/style workflows are running/queued; their results are pending.

Replay with python -m unittest azure.cli.command_modules.sql.tests.latest.test_sql_str_policy azure.cli.command_modules.sql.tests.latest.test_sql_mi_str_policy azure.cli.command_modules.sql.tests.latest.test_sql_db_str_policy in a configured developer checkout.

Live recording requirements and safety guards: SQL STR recording guidance.

• MI: AZURE_CLI_TEST_SQL_MI_RESOURCE_ID; irreversible locking additionally requires AZURE_CLI_TEST_SQL_MI_ALLOW_IMMUTABILITY_LOCK=true.
• New SQL DB: AZURE_CLI_TEST_SQL_SERVER_RESOURCE_ID; locking additionally requires AZURE_CLI_TEST_SQL_DB_ALLOW_IMMUTABILITY_LOCK=true. These runs used AZURE_CLI_TEST_SQL_DB_KEEP_DATABASES=true.
• Policy-only SQL DB: AZURE_CLI_TEST_SQL_DB_RESOURCE_ID plus separate irreversible-lock authorization. Requires Enabled and retention above one day; always retains the database.
• Missing recordings do not authorize live access. Do not run the entire SQL module live on shared resources. Local diagnostic cassettes are excluded from this PR.

History Notes
[SQL] az sql db str-policy: Add short-term backup immutability locking with confirmation and expose immutability status
[SQL] az sql midb short-term-retention-policy: Add immutability locking for live databases and expose status for live and dropped databases

This checklist is used to make sure that common guidelines for a pull request are followed.

• The PR title and description has followed the guideline in Submitting Pull Requests.
• I adhere to the Command Guidelines.
• I adhere to the Error Handling Guidelines.